<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8"/>
<link rel="stylesheet" type="text/css" href="resources/common.css"/>
<title>CSI Output: Metadata</title>
</head>
<body>
<div class="toptitle">CSI Guide</div>
<table class="toptable"><tr>
<td class="topprev"><a href="metadata_pt.html">&larr; Prev</a></td>
<td class="topnext"><a href="variables.html">Next &rarr;</a></td>
</tr></table>
<hr/>
<h1>CSI Output: Metadata</h1>
<hr class="half"/>
<h3>Call Coverage Details</h3>
<p>Call Coverage metadata is stored as text in the debug
section <samp>.debug_CC</samp> of the object file or executable.  Note
that in the case of multiple object files linked into a single
executable, the executable contains the complete metadata consolidated
from all object files.  To extract this data, use a command similar
to<br/>
<kbd class="indent">Tools/extract-section --require .debug_CC <var>myexe</var></kbd></p>

<p>The extracted information will contain entries for each instrumented function
in any object file linked into the executable.  Each entry gives information for
each call site in the function.  A complete example (from the unit test
<span class="unittest">funcs</span>) is:</p>
<pre class="indent">
#a|__CC_arr_a
0|20|printf
1|14|printf
2|17|abc
3|18|abc
4|19|abc
#b|__CC_arr_b
0|26|a
#main|__CC_arr_main
0|35|a
1|35|printf
2|36|b
3|36|printf
</pre>

<p>The format grammar follows.  <span class="nonterm">Non-terminals</span> are
distinguished from <span class="term">terminals</span> by capitalization, color,
and italics.</p>

<table class="grammar">
  <tbody>
    <tr>
      <td class="nonterm">Function_List</td>
      <td class="expansion">⩴</td>
      <td><span class="nonterm">Function</span> <span class="term">↵</span> <span class="nonterm">Function_List</span></td>
    </tr>
    <tr>
      <td/>
      <td class="alternative">|</td>
      <td class="term">ε</td>
    </tr>
  </tbody>
  <tbody>
    <tr>
      <td class="nonterm">Function</td>
      <td class="expansion">⩴</td>
      <td><span class="term"># fn-name | global-array-name ↵</span> <span class="nonterm">Call_List</span></td>
    </tr>
  </tbody>
  <tbody>
    <tr>
      <td class="nonterm">Call_List</td>
      <td class="expansion">⩴</td>
      <td><span class="nonterm">Call</span> <span class="term">↵</span> <span class="nonterm">Call_List</span></td>
    </tr>
    <tr>
      <td/>
      <td class="alternative">|</td>
      <td class="term">ε</td>
    </tr>
  </tbody>
  <tbody>
    <tr>
      <td class="nonterm">Call</td>
      <td class="expansion">⩴</td>
      <td><span class="term">array-index | line-num |</span> <span class="nonterm">Called_Function</span></td>
    </tr>
  </tbody>
  <tbody>
    <tr>
      <td class="nonterm">Called_Function</td>
      <td class="expansion">⩴</td>
      <td class="term">fn-name</td>
    </tr>
    <tr>
      <td/>
      <td class="alternative">|</td>
      <td class="term">?</td>
    </tr>
  </tbody>
</table>

<p>Each <span class="nonterm">Function</span> entry lists the function’s name
and the name of the global coverage array.  In the example above, then, function
<code>main</code>’s global array will be named <code>__CC_arr_main</code> in the
executing program.</p>

<p>The header is followed by <var>N</var> <span class="nonterm">Call</span>
lines each describing one of the <var>N</var> call sites in the function.  For
each call, the metadata lists the index of the call’s boolean flag (from 0
to <var>N</var>-1) in both the local and global coverage arrays, the line number
of the call, and the name of the <span class="nonterm">Called_Function</span>.
If the called function cannot be statically determined, the function name is
replaced with a
<span class="term">?</span>.  In the example above, then, there is a call to
function <code>abc</code> on line 17 within function <code>a</code>.  In a
running version of this program, the boolean value at <code>__CC_arr_a[2]</code>
(and the corresponding local variable <code>__CC_arr[2]</code>; see the
<a href="variables.html">variables</a> page), denotes whether or not the program
has previously executed and returned from this call.</p>

<hr/>
<table class="toptable"><tr>
<td class="topprev"><a href="metadata_pt.html">&larr; Prev</a></td>
<td class="topnext"><a href="variables.html">Next &rarr;</a></td>
</tr></table>
<div class="contents_link"><a href="index.html">Contents</a></div>
</body>
</html>
